home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / mcmm.exe / Q_GUIDE.TXT < prev   
Encoding:
Text File  |  1992-10-02  |  18.5 KB  |  530 lines
  1. Programmers Quick Guide to MCs Menu Maker v0.8
  2. ----------------------------------------------
  3.  
  4. Ok,so its not that quick a guide!,but there should be enough information here to
  5. allow use of the menus/windows without any further documentation.
  6. A list of all the functions that are necessary in order to create and maintain
  7. a menu and/or window structure are listed below.Example code to illustrate each
  8. call is also included,with a full working skeleton at the end of this
  9. documentation.Note:If a window is linked to a menu then on being displayed it
  10. will use its defaults however,if the window is displayed using window_show the
  11. gadget values are taken from the windows work area and therefore must be set
  12. first with win_set_item.Bascially if you *always* require the default values to
  13. be used then link the window to a menu otherwise you have to manage the window
  14. work area yourself (a demonstration of this in included at the end).
  15. Cursor keys allow up/down movement on the menus while tab allows input to
  16. circle around all a windows options.
  17.  
  18.  
  19. void menu_clear(int 1)
  20. ----------------------
  21.  
  22. Parameter 1 is a number representing the main background screen colour to be
  23. used.This function must be called first before any others as it contains code
  24. to initialize the menu/window system.
  25.  
  26. Example:
  27. --------
  28.  
  29. menu_clear(1);
  30.  
  31. Menu/window system will be initialized and main background colour will be 1,
  32. standard EGA/VGA 16 colour scheme is used (see documentation for list).
  33.  
  34.  
  35. void menu_declare(char *1)
  36. --------------------------
  37.  
  38. This call allows each possible selection on a menu to be declared.To link a
  39. particular option to a window the window number is contained in curly brackets
  40. before the option.Window and menu numbers are assigned depending on the order of
  41. declaration e.g. the first defined menu is menu 0 the second menu 1 etc, the
  42. same applies to windows.
  43.  
  44. Example:
  45. --------
  46.  
  47. menu_declare("A menu,{3}This option opens a window");
  48.  
  49. A menu will be defined,its number is dependant on if any other menus were
  50. created before it (as the above is an example of the first menu declaration its
  51. number will be 0).The first option in the menu will be the text "A menu" it has
  52. no direct link to a window,on selection it will set the global variables
  53. menu_option and menu_number,in this example both would equal 0 - for menu 0,
  54. option 0 selected.The second option would insert the text "This option opens a
  55. window",on selection window 3 would be openned and input would now be into this
  56. window.Note,no menus are actually displayed until a menu_display is issued.
  57.  
  58.  
  59. void window_declare(char *1,int 2,int 3,int 4,int 5,char *6)
  60. ------------------------------------------------------------
  61.  
  62. Allows a window to be defined.The order of declaration will define the window
  63. number.All window declarations must end in a curly bracketed 0.Parameter 1
  64. allows for an automatically centered window title to be displayed,if this is
  65. left as a null ("") then no title will be displayed.Parameters 2 and 3 are the
  66. windows size in characters (x,y).Parameters 4 and 5 determine the x,y coordinate
  67. to place the window at,if both are 0 then the window is placed below and
  68. slightly to the right (where ever possible) of the menu option that selected it.
  69. If either value is not 0 then the window is placed directly at these coordinates
  70. (origin top left 0,0).The final parameter 6 contains the window gadget types
  71. required,currently supported types are listed below.Note all x,y coordinates
  72. are relative to the windows origin.
  73.  
  74.         type 1 text (x,y,col,string)
  75.         Parameters x,y are the coordinates to place the text at.Col is the
  76.         colour to use to display text and finally string is the actual text
  77.         itself.
  78.  
  79.         Example:
  80.         --------
  81.  
  82.         "{1}{10}{9}{15}Some text"
  83.  
  84.         The text "Some text" will be displayed at coordinates 10,9 in colour
  85.         15.
  86.  
  87.  
  88.         type 2 switcher (x,y,num,def)
  89.         Parameters x,y are the coordinates to place the first switch at.Num is
  90.         the total number of switches displayed.Finally def is the number of the
  91.         default switch to be highlighted.
  92.  
  93.         Example:
  94.         --------
  95.  
  96.         "{2}{3}{4}{4}{2}"
  97.  
  98.         4 switches will be displayed starting at coordinates 3,4,switch 2 is
  99.         the default hence highlighted one.
  100.  
  101.  
  102.         type 3 number (x,y,min,max,def)
  103.         Parameters x,y are the coordinates to place the input box.Min and Max
  104.         define the minimum and maximum value to accept.Def is the default
  105.         value.
  106.  
  107.         Example:
  108.         --------
  109.  
  110.         "{3}{10}{11}{5}{10}{6}"
  111.  
  112.         An input box will displayed at coordinates 10,11,it will accept only
  113.         values between 5 and 10 inclusive.The default value is 6.
  114.  
  115.  
  116.         type 4 boolean (x,y,def)
  117.         Parameters x,y are the coordinates to place the alternator at.Def is
  118.         the default selection (1=Yes,0=No).
  119.  
  120.         Example:
  121.         --------
  122.  
  123.         "{4}{7}{4}{1}"
  124.  
  125.         A boolean alternator will be displayed at coordinates 7,4.Its default
  126.         will be YES.
  127.  
  128.  
  129.         type 5 file (x,y,height,type)
  130.         Parameters x,y are the coordinates to place the start of the file box
  131.         at.Height is the height of the box in characters.Type defines what
  132.         action to take on a selection,(0=exit on selection of file to calling
  133.         program,1=don't,this allows for just directory selection).The current
  134.         directory will be used.
  135.  
  136.         Example:
  137.         --------
  138.  
  139.         "{5}{6}{7}{10}{0}"
  140.  
  141.         A file selection box will be displayed at coordinates 6,7.Its height
  142.         will be 10 characters.On a file selection control will return to the
  143.         calling enviroment.
  144.  
  145.  
  146.         type 6 char (x,y,len,type,def)
  147.         Parameters x,y are the coordinates to place the start of the input box
  148.         at.Len is the maximum length of input string to accept.Type defines
  149.         what action to take on <return> being pressed,(0=normal, string is
  150.         stored but no action taken,1=exit on entry to calling program).Def is
  151.         the default string to be displayed.
  152.  
  153.         Example:
  154.         --------
  155.  
  156.         "{6}{17}{8}{10}{0}"
  157.  
  158.         An input box will be displayed at coordinates 17,8.Maximum input length
  159.         of string will be 10 characters.On <return> no action will result,apart
  160.         from storage of the string.
  161.  
  162.  
  163.         type 7 accept (x,y,text)
  164.         Parameters x,y are the coordinates to place the icon at.Text is the
  165.         actual icon text to display.
  166.  
  167.         Example:
  168.         --------
  169.  
  170.         "{7}{6}{22}OK"
  171.  
  172.         An icon will be displayed at coordinates 6,22.Its text will be "OK".
  173.  
  174.  
  175. Full Example:
  176. -------------
  177.  
  178. window_declare("A window",50,20,0,0,"{1}{2}{2}{9}Hi,{3}{2}{5}{2}{10}{5},{0}");
  179.  
  180. A window with title "A window" of size 50,20 will be declared.When displayed
  181. it will appear one character down and one character to the right of the menu
  182. option that selected it if possible.The text string "Hi" will be displayed in
  183. colour 9 at coordinates 2,2.A number input box will be displayed at coordinates
  184. 2,5 it will accept a value between 2 and 10 inclusive,with the default displayed
  185. value being 5.Note the {0} terminator.
  186.  
  187.  
  188. int window_show(int 1,int 2,int 3)
  189. ----------------------------------
  190.  
  191. Window with the number parameter 1 will be displayed at coordinates parameter
  192. 2,parameter 3.This allows windows to be used without a menu selection being
  193. made or without any menus at all.The returned value is either the ASCII code
  194. of a 'non-window' key or a status value (see documentation).Note:default gadget
  195. values are overwrote as any values are read from the gadgets work space.
  196.  
  197. Example:
  198. --------
  199.  
  200. key=window_show(5,10,10);
  201.  
  202. Display window 5 at coordinates 10,10.
  203.  
  204.  
  205. void window_help_declare(int 1,int 2,char *3)
  206. ---------------------------------------------
  207.  
  208. A window option must have a help string attached to it (null for none).
  209. Parameter 1 defines which window the help is attached to.Parameter 2 defines
  210. which gadget within that window the help is attached to.Parameter 3 is the
  211. help string to be displayed.Note a text gadget has no help string.
  212.  
  213. Example:
  214. --------
  215.  
  216. window_declare("",10,10,0,0,"{2}{1}{1}{2}{1},{5}{2}{4}{4}{1},{0}");
  217. window_help_declare(0,1,"Please select a file to load");
  218.  
  219. The window declaration defines a window with no title of size 10,10 and
  220. displayed slightly offset from its menu selection.A switcher is displayed at
  221. coordinates 1,1 with 2 switches and switch 1 the default.A file selector is also
  222. displayed at coordinates 2,4,its height is 4 characters.On any file selection no
  223. action is taken.The window_help_declare defines a help string for window 0
  224. (assuming the window defined above was the first),item 1 (the file selector) and
  225. finally the actual help text to appear.
  226.  
  227.  
  228. void menu_help_declare(int 1,int 2,char *3)
  229. -------------------------------------------
  230.  
  231. A menu option must have help text attached to it ("" for none).Parameter 1 
  232. defines which menu will have the help.Parameter 2 defines which option within 
  233. the menu will recieve the help.Parameter 3 is the actual help text.
  234.  
  235. Example:
  236. --------
  237.  
  238. menu_declare("{0}About,How to register");
  239. menu_help_declare(0,0,"All about this program");
  240. menu_help_declare(0,1,"");
  241.  
  242. The menu declaration defines a menu with two options,"About" links to window 0
  243. on selection and "How to register" has no link or help.The menu_help_declare 
  244. defines a help string for menu 0 (assuming the menu defined above was the 
  245. first),item 0 (the "About" string) and finally the help text for that option.
  246.  
  247.  
  248. void win_set_item(int 1,int 2,long int 3)
  249. -----------------------------------------
  250.  
  251. This allows a window gadgets value to be set.Parameter 1 specifies the window
  252. number.Parameter 2 specifies which item within that window.Parameter 3 is the
  253. value to set it to,int long is used so that the setting of addresses can be
  254. allowed.Settings would be thus:
  255.  
  256.         type 1 text
  257.         No setable parameters.
  258.  
  259.         type 2 switcher
  260.         A value indicating which switch is active.
  261.  
  262.         type 3 number
  263.         A value indicating the value to be displayed.
  264.  
  265.         type 4 boolean
  266.         A value indicating whether the setting is YES(1) or NO(0).
  267.  
  268.         type 5 file
  269.         The value here is an address to where the file selected is stored
  270.         (accessed with win_get_item),therefore this value should not be altered.
  271.         But the contents of its address will be the first character of the file
  272.         selected (0 terminated).
  273.  
  274.         type 6 char
  275.         The value here is an address to where the string is stored (accessed
  276.         with win_get_item),therefore this value should not be altered.But the
  277.         contents of its address will be the first character of the entered
  278.         string (0 terminated).
  279.  
  280.         type 7 accept
  281.         The value here is either a 1(icon selected) or a 0(not selected).Its the
  282.         user programs resposibility to reset an icon once its selection has been
  283.         dealt with.This is not necessary with only one icon in a window,but with
  284.         more all must be reset after a selection otherwise next time the window
  285.         is openned it will not be possible to determine which icon was selected.
  286.  
  287.  
  288. void menu_heading(void)
  289. -----------------------
  290.  
  291. This displays the menu heading which must have been previously defined with
  292. menu_bar_options.
  293.  
  294. Example:
  295. --------
  296.  
  297. menu_heading();
  298.  
  299. The menu headings are displayed.
  300.  
  301.  
  302. void menu_display(int 1)
  303. ------------------------
  304.  
  305. Parameter 1 defines which menu to display.This call is only of real use on a
  306. menu driven application being first executed i.e. forcing the user straight into
  307. a menu selection.
  308.  
  309. Example:
  310. --------
  311.  
  312. menu_display(3);
  313.  
  314. Display menu 3 on screen.
  315.  
  316.  
  317. int long win_get_item(int 1,int 2)
  318. ----------------------------------
  319.  
  320. The window numbered parameter 1,item parameter 2 returns a value (possibly an
  321. address) as a long integer.
  322.  
  323. Example:
  324. --------
  325.  
  326. value=win_get_item(5,3);
  327.  
  328. Value would contain the value of item 3 in window 5.
  329.  
  330.  
  331. int menu_poll(void)
  332. -------------------
  333.  
  334. Begins polling of the menus.The returned value is a 'non window' key.
  335.  
  336. Example:
  337. --------
  338.  
  339. key=menu_poll();
  340.  
  341. Polling of menus begins.Polling will be left when either a 'non window' key is
  342. pressed or a window gadgets type is such that it needs to return directly to the
  343. users program.
  344.  
  345.  
  346. void menu_kill(void)
  347. --------------------
  348.  
  349. This call must be issued once the application using the menus/windows ends,as
  350. any allocated memory during use is now released.
  351.  
  352. Example:
  353. --------
  354.  
  355. menu_kill();
  356.  
  357. All menu/window workspace memory is released.
  358.  
  359.  
  360. Useful Global Variables
  361. -----------------------
  362.  
  363. int menu_position          This always contains the currently selected menu
  364.  
  365. int menu_option            Contains the currently selected menu option
  366.  
  367. int menu_fore_color        The menu/window foreground color
  368.  
  369. int menu_back_color        The menu/window background color
  370.  
  371. int menu_highlight_color   The menu/window color for highlighted options/gadgets
  372.  
  373. char *menu_bar_options     The menu bar headings
  374.  
  375. int menu_help_color        Color for menu/window help text
  376.  
  377. int win_accept             Number of the currently active window
  378.  
  379. char menu_buffer1[4096]    Buffer to save screen behind menu
  380.  
  381. int win_out                User can set to 1,in order to leave menu poll loop
  382.  
  383.  
  384.  
  385. Example skeleton code
  386. ---------------------
  387.  
  388. To use the OBJ file include it in a project file along with your C source
  389. code plus of course any other object/source files.MCs Menu Maker uses far
  390. pointers therefore it will not work in tiny/small/medium memory models.
  391. The example below is very simple but illustrates how to use the various
  392. menu/window calls.The portion of code which displays the menu position and
  393. menu option may appear wrong after a selection is made and a different menu
  394. option highlighted,this is due to the way the screen updates and will not
  395. effect your own program.
  396.  
  397. #include "mcs_menu.h"                       //Include MCs Menu header
  398.  
  399. int menu_position=0;
  400. int menu_option=0;
  401. int menu_fore_color=15;                     //Foreground colour
  402. int menu_back_color=1;                        //Background colour
  403. int menu_highlight_color=4;                 //Highlight colour
  404. char menu_buffer1[4096];
  405. char menu_buffer2[4096];
  406. int menu_titles=0;
  407. char *menu_bar_options;
  408. int menu_menus=0;
  409. int window_windows=0;
  410. int window_x=0;
  411. int window_y=0;
  412. int win_attr=0;
  413. int win_out=0;
  414. char unsigned far *win_text_screen;
  415. int window_open=0;
  416. int window_item=0;
  417. int menu_help_color=14;
  418. int win_accept=0;
  419. int win_default=0;
  420. struct menu_help_def *startmh=NULL;
  421. struct menu_help_def *endmh=NULL;
  422. struct window_help_def *startwh=NULL;
  423. struct window_help_def *endwh=NULL;
  424. struct menu_def *start=NULL;
  425. struct menu_def *end=NULL;
  426. struct window_def *startw=NULL;
  427. struct window_def *endw=NULL;
  428.  
  429. void main (void)
  430. {
  431. int key,quit=0;
  432.  
  433. menu_clear(3);                              //Clear screen,get menu system ready
  434.  
  435.                         //Declare menu
  436. menu_declare("{0}Menu option 0,{1}Menu option 1,Menu option 2 has no window");
  437.  
  438. menu_help_declare(0,0,"This is a menu option");     //Declare help for this
  439. menu_help_declare(0,1,"");                          //menus options
  440. menu_help_declare(0,2,"This option has no window"); //
  441.  
  442.                         //Declare menu
  443. menu_declare("{0}Option 1,Option 2,Option 3,Option 4,EXIT");
  444.  
  445. menu_help_declare(1,0,"");                          //
  446. menu_help_declare(1,1,"");                          //Declare help for this
  447. menu_help_declare(1,2,"");                          //menus options
  448. menu_help_declare(1,3,"");                          //
  449. menu_help_declare(1,4,"Exit to DOS");               //
  450.  
  451.                                             //Declare windows
  452. window_declare(" A Sample Window ",74,12,0,0,"{1}{15}{2}{14}Some text,{2}{2}{1}{11}{4},{5}{8}{4}{6}{1},{0}");
  453. window_declare(" Another Window ",40,15,5,5,"{6}{3}{4}{15}{0}A text string,{3}{3}{8}{1}{10}{5},{1}{2}{7}{7}Enter a value between 1 and 10,{0}");
  454.  
  455.                                             //Menu heading titles
  456. menu_bar_options=" Menu-1         Menu-2 ";
  457.  
  458. menu_heading();                             //Display titles
  459.  
  460. gettext(1,1,80,25,menu_buffer1);            //Get background
  461.  
  462. menu_display(0);                            //Display a starting menu
  463.  
  464. do {
  465.  
  466.  
  467.   key=menu_poll();                          //Start polling the menus
  468.  
  469.   if (key==28)                              //BIOS code for 'Return' key
  470.   {
  471.    if (menu_position==1)                    //
  472.      if (menu_option==4)                    //If this option,exit
  473.        quit=1;                              //
  474.   }
  475.  
  476. gotoxy(10,20);                              //
  477. cprintf("menu selected: %d",menu_position); //
  478. gotoxy(10,21);                              //Display menu/option selected
  479. cprintf("menu option  : %d",menu_option);   //
  480. gotoxy(10,23);                              //
  481.  
  482. } while (quit==0);                          //Do until this flag is 1
  483.  
  484.  
  485. puttext(1,1,80,25,menu_buffer1);            //Put background back
  486.  
  487. }
  488.  
  489.  
  490.  
  491. Example of managing a window work area
  492. --------------------------------------
  493.  
  494. Assuming a window (number 6) has been declared and contains a switch as item 4
  495. and a char (input string) gadget as item 6,the following would set them, i.e.
  496. overriding any default.
  497.  
  498. char *addr;
  499. char p;
  500.  
  501. win_set_item(6,4,2);                        //Turn on switch 2
  502.  
  503. addr=(char *)win_get_item(6,6);             //Get the address where the type
  504.                                             //chars workspace is
  505.  
  506. for(p=0;p!=3;p++)                           //Although a rough example,this
  507.    *(addr+p)=p+65;                          //would fill the char workspace
  508.                                             //with A,B,C,D in succession
  509.  
  510.  
  511.  
  512. How to crash your PC!
  513. ---------------------
  514.  
  515. Its assumed that C programmers are reasonably intelligent (!),therefore doing
  516. things such as trying to create a window larger than the screen,trying to place
  517. a gadget at x coordinate 1 million,declaring a char gadget of length 6 and
  518. attempting to store a 500K file in it and such things are virtually guranteed to
  519. crash your system.Also declaring a window without a {0} terminator and a window
  520. or menu with a gadget type (e.g. {1} for text) and then the wrong number of
  521. corrosponding parameters will send your PC into a mild epiletic fit!!!.Failure
  522. to allocate memory and "simple" errors should be trapped by the menu system and
  523. return a useful error message.Remember its not perfect but it does work!,have
  524. fun.
  525.  
  526.  
  527. END: - 26/08/92 - Mark Hula -
  528. Compuserve id: 100047,110
  529.  
  530.